The Semantics

The Semantics

This section describes the semantics of the configuration file, including special macros, conditionals, special classes, and the "error" mailer.

Special Macros and Conditionals

Macros are interpolated by means of the construct $x, where x is the name of the macro to be interpolated. Special macros are named with lowercase letters; they either have special semantics or pass information into or out of sendmail. Some special characters are also reserved, and are used to provide conditionals and other functions.

The following syntax specifies a conditional:

$?x text1 $| text2 $.

This example interpolates text1 if the macro $x is set, and text2 otherwise.

The "else" ($|) clause can be omitted.

The following macros must be defined if information is to be transmitted into sendmail:

e: SMTP entry message, which prints out when STMP starts up
j: "official" domain name for this site; must be the first word of the $e macro
l: format of the UNIX "From" line; usually a constant
n: name of the daemon (for error messages); usually a constant
o: set of token operators in addresses
q: default format of sender address

The $o macro consists of a list of characters that are treated as tokens themselves and serve to separate tokens during parsing. For example, if @ were in the $o macro, then the input string "a@b" would scan as three tokens: a, @, and b.

Here are several examples of these macro definitions:

De$j Sendmail $v/$Z ready at $b
Dj$w
DlFrom $g  $d
DnMAILER-DAEMON
Do.:%@!^=/[]
Dq$g$?x ($x)$.

An acceptable alternative format for the $q macro is "$?x$x $.<$g>" . This syntax corresponds to the following two formats:

jd@company.com (John Doe)
John Doe <jd@company.com>

Some macros are defined by sendmail for interpolation into arguments passed to mailers or for other contexts. These macros are:

a: origination date in RFC 822 format
b: current date in RFC 822 format
c: hop count
d: date in UNIX (ctime) format
f: sender ("From") address
g: sender address relative to the recipient
h: recipient host
i: queue ID
p: PID for sendmail
r: protocol used
s: sender's hostname
t: a numeric representation of the current time
u: recipient user
v: version number of sendmail
w: hostname of this site
x: full name of the sender
z: home directory of the recipient

Macros $a, $b, and $d specify three dates that can be used. The $a and $b macros are in RFC 822 format. $a is the time extracted from the "Date:" line of the message; $b is the current date and time (used for postmarks). If no "Date:" line appears in the incoming message, $a is also set to the current time. The $d macro is equivalent to the $a macro in UNIX format (as described on the ctime(3C) reference page).

The $c macro is set to the "hop count," the number of times this message has been processed. It can be determined by the -h flag on the command line or by counting the time stamps in the message.

The $f macro is the ID of the sender as originally determined; when a message is sent to a specific host, the $g macro is set to the address of the sender relative to the recipient. For example, if jd sends to buddy@USomewhere.edu from the machine company.com, the $f macro will be jd and the $g macro will be jd@company.com.

When a message is sent, the $h, $u, and $z macros are set to the host, user, and home directory (if local) of the recipient. The first two are set from the $@ and $: part of the rewriting rules, respectively. The $i macro is set to the queue ID on this host; when included in the time-stamp line, it can be extremely useful for tracking messages.

The $p and $t macros are used to create unique strings (for example, for the Message-Id field). The $r and $s macros are set to the protocol used to communicate with sendmail and the name of the sending host; these macros are not supported in the current version.

The $v macro is set to be the version number of sendmail, which normally appears in time stamps and is extremely useful for debugging. The $w macro is set to the name of this host, if it can be determined.

The $x macro is set to the full name of the sender, derived from one of these sources (in this order):

a flag to sendmail
the value of the "Full-name:" line in the header if it exists
the comment field of a "From:" line
for messages originating locally, the value from the /etc/passwd file

Special Classes

The w class is the set of all names this host is known by, and can be used to match local hostnames.

The Left-Hand Side

The left-hand side of a rewriting rule contains a pattern. Words are simply matched directly. A dollar sign introduces the following meta-syntax:

$*: Match zero or more tokens.
$+: Match one or more tokens.
$-: Match exactly one token.
$=x: Match any token in class x.
$~x: Match any token not in class x.

If a match occurs, it is assigned to the symbol $n for replacement on the right-hand side, where n is the index in the lhs. For example, if the lhs

$-@$+

is applied to the input

jd@company.com

the rule will match, and the values passed to the rhs will be

$1: jd
$2: company.com

The Right-Hand Side

When the left-hand side of a rewriting rule matches, the input is deleted and replaced by the right-hand side. Right-hand-side tokens are inserted exactly as they appear unless they begin with a dollar sign. The meta-syntax is:

$n

Substitute indefinite token n from lhs; substitute the corresponding value from a $+, $-, $*, $=, or $~ match on the lhs; can be used anywhere.

$[hostname$]

Canonicalize hostname; a hostname enclosed between $[ and $] is looked up by the gethostbyname() routines and replaced by the canonical name. For example, $[frodo$] might become frodo.fantasy.com and $[[192.48.153.1]$] would become sgi.com. If gethostbyname() encounters an error, hostname will be returned unchanged.

$[name$:default$]

This is an extended version of the preceding construct, and provides a way to determine whether the canonicalization was successful. Using this syntax, the default is returned if the canonicalization step fails. For example, $[frodo$:FAIL$] becomes FAIL if gethostbyname() fails to canonicalize frodo.

$(x key$@arg$:default$)

Look up key in DBM or NIS database x. This is the database lookup syntax; x corresponds to a database previously declared using the K command (described in "Define Keyed Files--The K Command") and key is the string that should be searched for in the database. The arg and default arguments are optional. The default is returned if the key was not found in the database. If neither the default nor a matching key is found, the whole expression expands to the value of key. However, if a result is found, it is used as the format string of a sprintf() expression, with the arg as extra argument. Thus, database values with "%s" strings embedded in them can be useful when rewriting expressions. These values could typically be used with the pathalias program to expand routes without leaving sendmail.

${x query$:default$}

Look up query in DNS database x. This is the DNS database lookup syntax. The various values of x are internally defined and correspond to various DNS databases. The default argument is optional and will be returned if query cannot be found in the specified database.

The values for x are listed below.

@ Return MX record for query.
. As above, but use domain search rules.
: Return MR record for query.
? Return MB record for query.
c Expand query to its canonical name following MX records.
C As above, but use domain search rules.
h Like ${c but for A records.
H As above, but use domain search rules.

When domain search rules are requested, sendmail sets the RES_DNSRCH flag when calling the resolver. See the resolver(4) reference page for further information.

$>n

Call rule set n; causes the remainder of the line to be substituted as usual and then passed as the argument to rule set n. The final value of rule set n becomes the substitution for this construct.

Multiple calls can be embedded on the rhs. For example, $>32$>33$1 would make the substitution for $1 and pass the result to rule set 33. The result from rule set 33 would then be passed as the input to rule set 32. Finally, the entire construct would be replaced with the result from rule set 32.

Only embedded rule set calls in the form outlined above are supported. Rule sets calls cannot be arbitrarily placed within the rhs.

$#mailer$@host$:user

Resolve to mailer; the $# syntax should be used only in rule set 0. The syntax causes evaluation of the rule set to terminate immediately and signals sendmail that the address has completely resolved. This process specifies the {mailer, host, user} triple necessary to direct the mailer. If the mailer is local, the host part may be omitted. The mailer and host must be a single word, but the user may be a multi-part value.

An entire rhs may also be prefixed by a $@ or a $: to control evaluation.

The $@ prefix causes the rule set to return with the remainder of the rhs as the value. The $: prefix causes the rule to terminate immediately, but the rule set to continue; this can be used to avoid continued application of a rule. The prefix is stripped before continuing.

The $@ and $: prefixes may precede a $> specification. For example,

R$+     $:$>7$1

matches anything, passes that to rule set 7, and continues; the $: is necessary to avoid an infinite loop.

Substitution occurs in the order described: Parameters from the lhs are substituted, host names are canonicalized, "subroutines" are called, and finally $#, $@, and $: are processed.

Semantics of Rewriting Rule Sets

There are five rewriting rule sets that have specific semantics. Figure B-1 shows the relationship among these rule sets.

Figure B-1 : Semantics of Rewriting Rule Sets Rule set 3 should turn the address into canonical form. This form should have the following basic syntax:

local-part@host-domain-spec

If no "at" (@) sign is specified, then the host-domain-spec can be appended from the sender address (if the C flag is set in the mailer definition corresponding to the sending mailer). sendmail applies rule set 3 before doing anything with any address.

Next, rule set 0 is applied to an address that actually specifies recipients. The address must resolve to a {mailer, host, user} triple. The mailer must be defined in the mailer definitions from the configuration file. The host is defined into the $h macro for use in the argv expansion of the specified mailer.

Rule sets 1 and 2 are applied to all sender and recipient addresses, respectively. They are applied before any specification in the mailer definition. They must never resolve.

Rule set 4 is applied to all addresses in the message. It is typically used to translate from internal to external form.

The "error" Mailer

The mailer with the special name "error" can be used to generate a user error. The (optional) host field is a numeric exit status to be returned, and the user field is a message to be printed. For example, the following entry on the rhs of a rule causes the specified error to be generated if the lhs match:

$#error$:Host unknown in this domain

This mailer is functional only in rule set 0.

@	Return MX record for query.
.	As above, but use domain search rules.
:	Return MR record for query.
?	Return MB record for query.
c	Expand query to its canonical name following MX records.
C	As above, but use domain search rules.
h	Like ${c but for A records.
H	As above, but use domain search rules.